package com.kexio.enterprise.integration.file;

import com.kexio.enterprise.integration.common.PageResult;
import com.kexio.enterprise.integration.file.domain.FileInfo;
import com.kexio.enterprise.integration.file.metadata.FileMetadata;
import com.kexio.enterprise.integration.file.query.FileSearchCriteria;
import com.kexio.enterprise.integration.file.result.FileDownloadResult;
import com.kexio.enterprise.integration.file.result.FileUploadResult;
import com.kexio.enterprise.integration.file.statistics.StorageStatistics;

import java.io.InputStream;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 文件存储服务接口
 * 
 * 提供统一的文件存储抽象，支持多种存储后端
 * 
 * @author Kexio
 * @since 1.0.0
 */
public interface FileService {

    /**
     * 上传文件
     * 
     * @param fileInfo 文件信息
     * @return 文件上传结果
     */
    FileUploadResult uploadFile(FileInfo fileInfo);

    /**
     * 上传文件（从输入流）
     * 
     * @param fileName    文件名
     * @param inputStream 输入流
     * @param contentType 内容类型
     * @return 文件上传结果
     */
    FileUploadResult uploadFile(String fileName, InputStream inputStream, String contentType);

    /**
     * 上传文件（从字节数组）
     * 
     * @param fileName    文件名
     * @param fileBytes   文件字节数组
     * @param contentType 内容类型
     * @return 文件上传结果
     */
    FileUploadResult uploadFile(String fileName, byte[] fileBytes, String contentType);

    /**
     * 下载文件
     * 
     * @param fileId 文件ID
     * @return 文件下载结果
     */
    FileDownloadResult downloadFile(String fileId);

    /**
     * 下载文件（根据路径）
     * 
     * @param filePath 文件路径
     * @return 文件下载结果
     */
    FileDownloadResult downloadFileByPath(String filePath);

    /**
     * 删除文件
     * 
     * @param fileId 文件ID
     * @return 是否成功
     */
    boolean deleteFile(String fileId);

    /**
     * 删除文件（根据路径）
     * 
     * @param filePath 文件路径
     * @return 是否成功
     */
    boolean deleteFileByPath(String filePath);

    /**
     * 批量删除文件
     * 
     * @param fileIds 文件ID列表
     * @return 删除结果映射
     */
    Map<String, Boolean> batchDeleteFiles(List<String> fileIds);

    /**
     * 获取文件信息
     * 
     * @param fileId 文件ID
     * @return 文件元数据
     */
    FileMetadata getFileMetadata(String fileId);

    /**
     * 获取文件信息（根据路径）
     * 
     * @param filePath 文件路径
     * @return 文件元数据
     */
    FileMetadata getFileMetadataByPath(String filePath);

    /**
     * 搜索文件
     * 
     * @param criteria 搜索条件
     * @return 文件列表
     */
    List<FileMetadata> searchFiles(FileSearchCriteria criteria);

    /**
     * 分页搜索文件
     * 
     * @param criteria 搜索条件
     * @param page     页码（从0开始）
     * @param size     页大小
     * @return 分页结果
     */
    PageResult<FileMetadata> searchFiles(FileSearchCriteria criteria, int page, int size);

    /**
     * 复制文件
     * 
     * @param sourceFileId 源文件ID
     * @param targetPath   目标路径
     * @return 复制结果
     */
    FileUploadResult copyFile(String sourceFileId, String targetPath);

    /**
     * 移动文件
     * 
     * @param fileId     文件ID
     * @param targetPath 目标路径
     * @return 是否成功
     */
    boolean moveFile(String fileId, String targetPath);

    /**
     * 检查文件是否存在
     * 
     * @param fileId 文件ID
     * @return 是否存在
     */
    boolean fileExists(String fileId);

    /**
     * 检查文件是否存在（根据路径）
     * 
     * @param filePath 文件路径
     * @return 是否存在
     */
    boolean fileExistsByPath(String filePath);

    /**
     * 获取文件访问URL
     * 
     * @param fileId     文件ID
     * @param expireTime 过期时间（分钟）
     * @return 访问URL
     */
    String getFileUrl(String fileId, int expireTime);

    /**
     * 获取文件预览URL
     * 
     * @param fileId 文件ID
     * @return 预览URL
     */
    String getPreviewUrl(String fileId);

    /**
     * 更新文件元数据
     * 
     * @param fileId   文件ID
     * @param metadata 元数据
     * @return 是否成功
     */
    boolean updateFileMetadata(String fileId, Map<String, String> metadata);

    /**
     * 获取存储统计信息
     * 
     * @param storageType 存储类型
     * @param bucket      存储桶
     * @return 统计信息
     */
    StorageStatistics getStorageStatistics(String storageType, String bucket);

    /**
     * 获取全局存储统计信息
     * 
     * @return 统计信息
     */
    StorageStatistics getGlobalStorageStatistics();

    /**
     * 清理临时文件
     * 
     * @param beforeTime 清理时间点之前的文件
     * @return 清理的文件数量
     */
    int cleanupTempFiles(LocalDateTime beforeTime);

    /**
     * 清理过期文件
     * 
     * @param beforeTime 清理时间点之前的文件
     * @return 清理的文件数量
     */
    int cleanupExpiredFiles(LocalDateTime beforeTime);

    /**
     * 重命名文件
     * 
     * @param fileId  文件ID
     * @param newName 新文件名
     * @return 是否成功
     */
    boolean renameFile(String fileId, String newName);

    /**
     * 生成预签名URL
     * 
     * @param fileId       文件ID
     * @param expireMinutes 过期时间（分钟）
     * @return 预签名URL
     */
    String generatePresignedUrl(String fileId, int expireMinutes);

    /**
     * 生成上传预签名URL
     * 
     * @param fileName      文件名
     * @param contentType   内容类型
     * @param expireMinutes 过期时间（分钟）
     * @return 上传预签名URL
     */
    String generateUploadPresignedUrl(String fileName, String contentType, int expireMinutes);

    /**
     * 列出目录中的文件
     * 
     * @param directoryPath 目录路径
     * @return 文件列表
     */
    List<FileMetadata> listFiles(String directoryPath);

    /**
     * 分页列出目录中的文件
     * 
     * @param directoryPath 目录路径
     * @param page          页码（从0开始）
     * @param size          页大小
     * @return 分页结果
     */
    PageResult<FileMetadata> listFiles(String directoryPath, int page, int size);
}
